EnigmA Amiga Run 1997 July/EnigmA AMIGA RUN 20 (1997)(G.R. Edizioni)(IT)[!][issue 1997-07 & 08][EAR-CD IV].iso/lightwave/lwmlist/96.lightwave-0401/[e-mail] _Tue Apr 2 03:49:33 1996.msg

Internet Message Format | 1996-04-08 | 6KB

Received: from e55.webcom.com (e55.webcom.com [206.2.192.66]) by keeper.albany.net (8.7.5/8.7.5-MZ) with ESMTP id DAA05320 for <[e-mail]>; Tue, 2 Apr 1996 03:49:32 -0500 (EST)
Received: from localhost by e55.webcom.com with SMTP
    (1.37.109.15/16.2) id AA058594955; Tue, 2 Apr 1996 00:49:15 -0800
Date: Tue, 2 Apr 1996 00:49:15 -0800
Errors-To: [e-mail]
Message-Id: <[e-mail]>
Errors-To: [e-mail]
Reply-To: [e-mail]
Originator: [e-mail]
Sender: [e-mail]
Precedence: bulk
From: [e-mail]
To: [e-mail]
Subject: tech manual quality (long post)
X-Listprocessor-Version: 6.0c -- ListProcessor by Anastasios Kotsikonas
Status: RO
X-Status:

Wow, this was manuals criticism day, wasn't it?

For example,

on Sun, 31 Mar 1996 Mike McCool wrote:

> On Sun, 31 Mar 1996 [e-mail] wrote:
>
>>     Please note that most requests of this kind are >probably< from pirates.
>>
>>     Death to them all.
>
> Couldn't agree more.  But . . .  I'm a 3.0 lightwaver, and my manual is a
> goddam nightmare to use.  I'm afraid this is the case for EVERY piece of
> software I own:  the manuals are inexcusably bad.

The 4.0 manual is much better, although I am not completely satisfied with
it. The main thanks for the improvements go to John Gross, Bruce Branbit, and
Brad Peebler who wrote most of it. James Hebert also worked very hard on
putting all the pieces together.

> What's with all of us cyber-dweebs?  Did we sleep through basic grammar
> classes?  Is verbal composition something completely beyond us?
>
> There can be no excuse for piracy--but nor is there any excuse for guys
> melting their hearts and souls into a beautiful code for a beautiful
> piece of software and then going the cheapshit route for the manual.
>
> Just bought Aladdin4D.  I admit I bought it used, from a registered owner.
> And again, a nice piece of software,--but a manual that might have been
> written by morons.  Lopsided education, that develops such brilliant
> technical and creative abilities, but neglects basic communication
> skills.
>
> "ENGLISH" is not taboo subject--yet I know an amazing number of people
> who took NO English classes whatsoever in their entire college career,
> and yet they imagine themselves to be quite well-educated.  And so they
> appear to be--till the time comes for them to communicate by writing.
>
> So, that's why I am always on the lookout for EVERY tutorial and
> after-market user's manual I can find.  Since the developers seem to be
> too condescending to bother, filling in the gaps continues to be the task
> of the end user.

This isn't true in the LW case--Allen, Stuart, and all the developement team
care that the manuals are good; however, it isn't their responcibility to
write them, and I think it's better that way. They should spend their time
programming, and a professional writer would do a better job anyway.

> And to all of you who share your tips and strategies, who take the
> trouble to actually write how-to's, kudos and more kudos.

Thanks from me too.

And then there was:

on Sun, 31 Mar 1996 from Ernest Gusella:

> Mike McCool's message about English is straight and to the point.  I
> teach Computer Imaging in the Art Department at the University of South
> Florida- on Amigas!  In order to equip students for the real world, I
> attempt to get them to research projects, write about what they are
> doing, etc.  Instead, most of them are content to jam with the mouse, and
> will only open up a manual if everything else fails.  I have taken
>  ...
> world and its' history, how can they model it.  At least some of the
> people on this news group like Mike McCool recognize their own
> shortcomings and are attempting to do something about it.  This is the
> ...

To which was added

on Sun, 31 Mar 96 by [e-mail]

> Cyber-dweebs, nor even programmers, should[n't] be writing manuals unless
> they are skilled in doing so.  There are PLENTY of people who have college
> degrees in Technical Communications who can write a clear manual.  It is a
> question of management hiring such people/firms and giving them the
resources,
> including TIME, to write the manuals.  Simple really.

Actually, it's not that easy to find PLENTY of good writers in Topeka. In
fact, I am currently NewTek's only tech writer and I work "remotely" from San
Jose and only part-time. I believe management at NewTek cares that our
manuals are good. You are right that time and resources are very important to
a well written manual.

In fact, if you're looking for work as a tech writer, talk to NewTek; if
you're right for the job, you stand a good chance of getting hired.

> People seem to think that the program is just the code:  to me the
> program is the code, the design , AND the documentation & other ancillary
> bits that go with the product.

I agree completely.

If anyone reading this list has any SPECIFIC suggestions, corrections, ideas
FOR THE MANUALS, please send them to me. ([e-mail]) ("Please make
'em really good" doesn't count.)

Some people do seem to like the new manuals. Such as

on Sun, 31 Mar 1996 Ted Stethem

>  ...
> steamed, since he is still mainly with the Amiga and the Flyer, that the
> Intel version of LW 4.0 standalone came with such incredibly impressive
> manuals. He said his Toaster version came in with what virtually amounted
>  ...

and

on Mar 31 1996 from Larry Shultz:

> One of the problems with trying to document tools is
> how do you anticipate what someone will do with those tools.
>  ...
> I think you would agree that the Lightwave manual is much
> better than Aladdins.
>  ...

Thank you all for your comments. I am listening.

David Hibsher
Technical Writer, NewTek